   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Menubar
=======

 - Variable: current-menubar
     This variable holds the description of the current menubar.  This
     may be buffer-local.  When the menubar is changed, the function
     `set-menubar-dirty-flag' has to be called in order for the menubar
     to be updated on the screen.

 - Constant: default-menubar
     This variable holds the menubar description of the menubar that is
     visible at startup.  This is the value that `current-menubar' has
     at startup.

 - Function: set-menubar-dirty-flag
     This function tells XEmacs that the menubar widget has to be
     updated.  Changes to the menubar will generally not be visible
     until this function is called.

   The following convenience functions are provided for setting the
menubar.  They are equivalent to doing the appropriate action to change
`current-menubar', and then calling `set-menubar-dirty-flag'.  Note
that these functions copy their argument using `copy-sequence'.

 - Function: set-menubar MENUBAR
     This function sets the default menubar to be MENUBAR (see Menu Format.).
     This is the menubar that will be visible in buffers
     that have not defined their own, buffer-local menubar.

 - Function: set-buffer-menubar MENUBAR
     This function sets the buffer-local menubar to be MENUBAR.  This
     does not change the menubar in any buffers other than the current
     one.

   Miscellaneous:

 - Variable: menubar-show-keybindings
     If true, the menubar will display keyboard equivalents.  If false,
     only the command names will be displayed.

 - Variable: activate-menubar-hook
     Function or functions called before a menubar menu is pulled down.
     These functions are called with no arguments, and should
     interrogate and modify the value of `current-menubar' as desired.

     The functions on this hook are invoked after the mouse goes down,
     but before the menu is mapped, and may be used to activate,
     deactivate, add, or delete items from the menus.  However, using a
     filter (with the `:filter' keyword in a menu description) is
     generally a more efficient way of accomplishing the same thing,
     because the filter is invoked only when the actual menu goes down.
     With a complex menu, there can be a quite noticeable and
     sometimes aggravating delay if all menu modification is
     implemented using the `activate-menubar-hook'.  See above.

     These functions may return the symbol `t' to assert that they have
     made no changes to the menubar.  If any other value is returned,
     the menubar is recomputed.  If `t' is returned but the menubar has
     been changed, then the changes may not show up right away.
     Returning `nil' when the menubar has not changed is not so bad;
     more computation will be done, but redisplay of the menubar will
     still be performed optimally.

 - Variable: menu-no-selection-hook
     Function or functions to call when a menu or dialog box is
     dismissed without a selection having been made.

Modifying Menus
===============

   The following functions are provided to modify the menubar of one of
its submenus.  Note that these functions modify the menu in-place,
rather than copying it and making a new menu.

   Some of these functions take a "menu path", which is a list of
strings identifying the menu to be modified.  For example, `("File")'
names the top-level "File" menu.  `("File" "Foo")' names a hypothetical
submenu of "File".

   Others take a "menu item path", which is similar to a menu path but
also specifies a particular item to be modified.  For example, `("File"
"Save")' means the menu item called "Save" under the top-level "File"
menu.  `("Menu" "Foo" "Item")' means the menu item called "Item" under
the "Foo" submenu of "Menu".

 - Function: add-submenu MENU-PATH SUBMENU &optional BEFORE
     This function adds a menu to the menubar or one of its submenus.
     If the named menu exists already, it is changed.

     MENU-PATH identifies the menu under which the new menu should be
     inserted.  If MENU-PATH is `nil', then the menu will be added to
     the menubar itself.

     SUBMENU is the new menu to add (see Menu Format.).

     BEFORE, if provided, is the name of a menu before which this menu
     should be added, if this menu is not on its parent already.  If
     the menu is already present, it will not be moved.

 - Function: add-menu-button MENU-PATH MENU-LEAF &optional BEFORE
     This function adds a menu item to some menu, creating the menu
     first if necessary.  If the named item exists already, it is
     changed.

     MENU-PATH identifies the menu under which the new menu item should
     be inserted.

     MENU-LEAF is a menubar leaf node (see Menu Format.).

     BEFORE, if provided, is the name of a menu before which this item
     should be added, if this item is not on the menu already.  If the
     item is already present, it will not be moved.

 - Function: delete-menu-item MENU-ITEM-PATH
     This function removes the menu item specified by MENU-ITEM-PATH
     from the menu hierarchy.

 - Function: enable-menu-item MENU-ITEM-PATH
     This function makes the menu item specified by MENU-ITEM-PATH be
     selectable.

 - Function: disable-menu-item MENU-ITEM-PATH
     This function makes the menu item specified by MENU-ITEM-PATH be
     unselectable.

 - Function: relabel-menu-item MENU-ITEM-PATH NEW-NAME
     This function changes the string of the menu item specified by
     MENU-ITEM-PATH.  NEW-NAME is the string that the menu item will be
     printed as from now on.

   The following function can be used to search for a particular item in
a menubar specification, given a path to the item.

 - Function: find-menu-item MENUBAR MENU-ITEM-PATH &optional PARENT
     This function searches MENUBAR for the item given by
     MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
     of MENUBAR).  This function returns `(ITEM . PARENT)', where
     PARENT is the immediate parent of the item found (a menu
     description), and ITEM is either a vector, list, or string,
     depending on the nature of the menu item.

     This function signals an error if the item is not found.

   The following deprecated functions are also documented, so that
existing code can be understood.  You should not use these functions in
new code.

 - Function: add-menu MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE
     This function adds a menu to the menubar or one of its submenus.
     If the named menu exists already, it is changed.  This is
     obsolete; use `add-submenu' instead.

     MENU-PATH identifies the menu under which the new menu should be
     inserted.  If MENU-PATH is `nil', then the menu will be added to
     the menubar itself.

     MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
     a list of menu items, strings, and submenus.  These two arguments
     are the same as the first and following elements of a menu
     description (see Menu Format.).

     BEFORE, if provided, is the name of a menu before which this menu
     should be added, if this menu is not on its parent already.  If the
     menu is already present, it will not be moved.

 - Function: add-menu-item MENU-PATH ITEM-NAME FUNCTION ENABLED-P
          &optional BEFORE
     This function adds a menu item to some menu, creating the menu
     first if necessary.  If the named item exists already, it is
     changed.  This is obsolete; use `add-menu-button' instead.

     MENU-PATH identifies the menu under which the new menu item should
     be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
     second, and third elements of a menu item vector (see Menu Format.).

     BEFORE, if provided, is the name of a menu item before which this
     item should be added, if this item is not on the menu already.  If
     the item is already present, it will not be moved.

Menu Filters
============

   The following filter functions are provided for use in
`default-menubar'.  You may want to use them in your own menubar
description.

 - Function: file-menu-filter MENU-ITEMS
     This function changes the arguments and sensitivity of these File
     menu items:

    `Delete Buffer'
          Has the name of the current buffer appended to it.

    `Print Buffer'
          Has the name of the current buffer appended to it.

    `Pretty-Print Buffer'
          Has the name of the current buffer appended to it.

    `Save Buffer'
          Has the name of the current buffer appended to it, and is
          sensitive only when the current buffer is modified.

    `Revert Buffer'
          Has the name of the current buffer appended to it, and is
          sensitive only when the current buffer has a file.

    `Delete Frame'
          Sensitive only when there is more than one visible frame.

 - Function: edit-menu-filter MENU-ITEMS
     This function changes the arguments and sensitivity of these Edit
     menu items:

    `Cut'
          Sensitive only when XEmacs owns the primary X Selection (if
          `zmacs-regions' is `t', this is equivalent to saying that
          there is a region selected).

    `Copy'
          Sensitive only when XEmacs owns the primary X Selection.

    `Clear'
          Sensitive only when XEmacs owns the primary X Selection.

    `Paste'
          Sensitive only when there is an owner for the X Clipboard
          Selection.

    `Undo'
          Sensitive only when there is undo information.  While in the
          midst of an undo, this is changed to `Undo More'.

 - Function: buffers-menu-filter MENU-ITEMS
     This function sets up the Buffers menu.  See Buffers Menu for
     more information.

Pop-Up Menus
============

 - Function: popup-menu MENU-DESC
     This function pops up a menu specified by MENU-DESC, which is a
     menu description (see Menu Format.).  The menu is displayed at
     the current mouse position.

 - Function: popup-menu-up-p
     This function returns `t' if a pop-up menu is up, `nil' otherwise.

 - Variable: popup-menu-titles
     If true (the default), pop-up menus will have title bars at the
     top.

   Some machinery is provided that attempts to provide a higher-level
mechanism onto pop-up menus.  This only works if you do not redefine
the binding for button3.

 - Command: popup-mode-menu
     This function pops up a menu of global and mode-specific commands.
     The menu is computed by combining `global-popup-menu' and
     `mode-popup-menu'.  This is the default binding for button3.  You
     should generally not change this binding.

 - Variable: global-popup-menu
     This holds the global popup menu.  This is present in all modes.
     (This is `nil' by default.)

 - Variable: mode-popup-menu
     The mode-specific popup menu.  Automatically buffer local.  This
     is appended to the default items in `global-popup-menu'.

 - Constant: default-popup-menu
     This holds the default value of `mode-popup-menu'.

 - Variable: activate-popup-menu-hook
     Function or functions run before a mode-specific popup menu is made
     visible.  These functions are called with no arguments, and should
     interrogate and modify the value of `global-popup-menu' or
     `mode-popup-menu' as desired.  Note: this hook is only run if you
     use `popup-mode-menu' for activating the global and mode-specific
     commands; if you have your own binding for button3, this hook
     won't be run.

   The following convenience functions are provided for displaying
pop-up menus.

 - Function: popup-buffer-menu EVENT
     This function pops up a copy of the `Buffers' menu (from the
     menubar) where the mouse is clicked.

 - Function: popup-menubar-menu EVENT
     This function pops up a copy of menu that also appears in the
     menubar.

Menu Accelerators
=================

   Menu accelerators are keyboard shortcuts for accessing the menubar.
Accelerator keys can be specified for menus as well as for menu items.
An accelerator key for a menu is used to activate that menu when it
appears as a submenu of another menu.  An accelerator key for a menu
item is used to activate that item.

Creating Menu Accelerators
--------------------------

   Menu accelerators are specified as part of the menubar format using
the :accelerator tag to specify a key or by placing "%_" in the menu or
menu item name prior to the letter which is to be used as the
accelerator key.  The advantage of the second method is that the menu
rendering code then knows to draw an underline under that character,
which is the canonical way of indicating an accelerator key to a user.

   For example, the command

     (add-submenu nil '("%_Test"
     		   ["One" (insert "1") :accelerator ?1 :active t]
     		   ["%_Two" (insert "2") t]
     		   ["%_3" (insert "3") t]))

   will add a new menu to the top level menubar.  The new menu can be
reached by pressing "t" while the top level menubar is active.  When
the menu is active, pressing "1" will activate the first item and
insert the character "1" into the buffer.  Pressing "2" will activate
the second item and insert the character "2" into the buffer.  Pressing
"3" will activate the third item and insert the character "3" into the
buffer.

   It is possible to activate the top level menubar itself using
accelerator keys.  See Menu Accelerator Functions.

Keyboard Menu Traversal
-----------------------

   In addition to immediately activating a menu or menu item, the
keyboard can be used to traverse the menus without activating items.
The keyboard arrow keys, the return key and the escape key are defined
to traverse the menus in a way that should be familiar to users of any
of a certain family of popular PC operating systems.

   This behaviour can be changed by modifying the bindings in
menu-accelerator-map.  At this point, the online help is your best bet
for more information about how to modify the menu traversal keys.

Menu Accelerator Functions
--------------------------

 - Function: accelerate-menu
     Make the menubar immediately active and place the cursor on the
     left most entry in the top level menu.  Menu items can be selected
     as usual.

 - Variable: menu-accelerator-enabled
     Whether menu accelerator keys can cause the menubar to become
     active.

     If `menu-force' or `menu-fallback', then menu accelerator keys can
     be used to activate the top level menu.  Once the menubar becomes
     active, the accelerator keys can be used regardless of the value
     of this variable.

     `menu-force' is used to indicate that the menu accelerator key
     takes precedence over bindings in the current keymap(s).
     `menu-fallback' means that bindings in the current keymap take
     precedence over menu accelerator keys.  Thus a top level menu with
     an accelerator of "T" would be activated on a keypress of Meta-t
     if MENU-ACCELERATOR-ENABLED is `menu-force'.  However, if
     MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
     activate the menubar and will instead run the function
     transpose-words, to which it is normally bound.

     The default value is `nil'.

     See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.

 - Variable: menu-accelerator-map
     Keymap consulted to determine the commands to run in response to
     keypresses occurring while the menubar is active.  See Keyboard Menu Traversal.

 - Variable: menu-accelerator-modifiers
     A list of modifier keys which must be pressed in addition to a
     valid menu accelerator in order for the top level menu to be
     activated in response to a keystroke.  The default value of
     `(meta)' mirrors the useage of the alt key as a menu accelerator
     in popular PC operating systems.

     The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
     the modifiers present in the keypress.  The only exception is that
     the shift modifier is accepted in conjunction with alphabetic keys
     even if it is not a menu accelerator modifier.

     See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.

 - Variable: menu-accelerator-prefix
     Prefix key(s) that must be typed before menu accelerators will be
     activated.  Must be a valid key descriptor.

     The default value is `nil'.

     (setq menu-accelerator-prefix ?\C-x)
     (setq menu-accelerator-modifiers '(meta control))
     (setq menu-accelerator-enabled 'menu-force)
     (add-submenu nil '("%_Test"
     		   ["One" (insert "1") :accelerator ?1 :active t]
     		   ["%_Two" (insert "2") t]
     		   ["%_3" (insert "3") t]))

   will add the menu "Test" to the top level menubar.  Pressing C-x
followed by C-M-T will activate the menubar and display the "Test"
menu.  Pressing C-M-T by itself will not activate the menubar.  Neither
will pressing C-x followed by anything else.

Buffers Menu
============

   The following options control how the `Buffers' menu is displayed.
This is a list of all (or a subset of) the buffers currently in
existence, and is updated dynamically.

 - User Option: buffers-menu-max-size
     This user option holds the maximum number of entries which may
     appear on the `Buffers' menu.  If this is 10, then only the ten
     most-recently-selected buffers will be shown.  If this is `nil',
     then all buffers will be shown.  Setting this to a large number or
     `nil' will slow down menu responsiveness.

 - Function: format-buffers-menu-line BUFFER
     This function returns a string to represent BUFFER in the
     `Buffers' menu.  `nil' means the buffer shouldn't be listed.  You
     can redefine this.

 - User Option: complex-buffers-menu-p
     If true, the `Buffers' menu will contain several commands, as
     submenus of each buffer line.  If this is false, then there will
     be only one command: select that buffer.

 - User Option: buffers-menu-switch-to-buffer-function
     This user option holds the function to call to select a buffer
     from the `Buffers' menu.  `switch-to-buffer' is a good choice, as
     is `pop-to-buffer'.

Dialog Boxes
************

Dialog Box Format
=================

   A dialog box description is a list.

   * The first element of the list is a string to display in the dialog
     box.

   * The rest of the elements are descriptions of the dialog box's
     buttons.  Each one is a vector of three elements:
        - The first element is the text of the button.

        - The second element is the "callback".

        - The third element is `t' or `nil', whether this button is
          selectable.

   If the callback of a button is a symbol, then it must name a command.
It will be invoked with `call-interactively'.  If it is a list, then it
is evaluated with `eval'.

   One (and only one) of the buttons may be `nil'.  This marker means
that all following buttons should be flushright instead of flushleft.

   The syntax, more precisely:

        form		:=  <something to pass to `eval'>
        command	:=  <a symbol or string, to pass to `call-interactively'>
        callback 	:=  command | form
        active-p	:=  <t, nil, or a form to evaluate to decide whether this
     		    button should be selectable>
        name		:=  <string>
        partition	:=  'nil'
        button	:=  '['  name callback active-p ']'
        dialog	:=  '(' name [ button ]+ [ partition [ button ]+ ] ')'

Dialog Box Functions
====================

 - Function: popup-dialog-box DBOX-DESC
     This function pops up a dialog box.  DBOX-DESC describes how the
     dialog box will appear (see Dialog Box Format.).

   See Yes-or-No Queries, for functions to ask a yes/no question
using a dialog box.

Toolbar
*******

Toolbar Intro
=============

   A "toolbar" is a bar of icons displayed along one edge of a frame.
You can view a toolbar as a series of menu shortcuts - the most common
menu options can be accessed with a single click rather than a series
of clicks and/or drags to select the option from a menu.  Consistent
with this, a help string (called the "help-echo") describing what an
icon in the toolbar (called a "toolbar button") does, is displayed in
the minibuffer when the mouse is over the button.

   In XEmacs, a toolbar can be displayed along any of the four edges of
the frame, and two or more different edges can be displaying toolbars
simultaneously.  The contents, thickness, and visibility of the
toolbars can be controlled separately, and the values can be
per-buffer, per-frame, etc., using specifiers (see Specifiers.).

   Normally, there is one toolbar displayed in a frame.  Usually, this
is the standard toolbar, but certain modes will override this and
substitute their own toolbar.  In some cases (e.g. the VM package), a
package will supply its own toolbar along a different edge from the
standard toolbar, so that both can be visible at once.  This standard
toolbar is usually positioned along the top of the frame, but this can
be changed using `set-default-toolbar-position'.

   Note that, for each of the toolbar properties (contents, thickness,
and visibility), there is a separate specifier for each of the four
toolbar positions (top, bottom, left, and right), and an additional
specifier for the "default" toolbar, i.e. the toolbar whose position is
controlled by `set-default-toolbar-position'.  The way this works is
that `set-default-toolbar-position' arranges things so that the
appropriate position-specific specifiers for the default position
inherit from the corresponding default specifiers.  That way, if the
position-specific specifier does not give a value (which it usually
doesn't), then the value from the default specifier applies.  If you
want to control the default toolbar, you just change the default
specifiers, and everything works.  A package such as VM that wants to
put its own toolbar in a different location from the default just sets
the position-specific specifiers, and if the user sets the default
toolbar to the same position, it will just not be visible.

Toolbar Descriptor Format
=========================

   The contents of a toolbar are specified using a "toolbar descriptor".
The format of a toolbar descriptor is a list of "toolbar button
descriptors".  Each toolbar button descriptor is a vector in one of the
following formats:

   * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'

   * `[:style 2D-OR-3D]'

   * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'

   * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'

   Optionally, one of the toolbar button descriptors may be `nil'
instead of a vector; this signifies the division between the toolbar
buttons that are to be displayed flush-left, and the buttons to be
displayed flush-right.

   The first vector format above specifies a normal toolbar button; the
others specify blank areas in the toolbar.

   For the first vector format:

   * GLYPH-LIST should be a list of one to six glyphs (as created by
     `make-glyph') or a symbol whose value is such a list.  The first
     glyph, which must be provided, is the glyph used to display the
     toolbar button when it is in the "up" (not pressed) state.  The
     optional second glyph is for displaying the button when it is in
     the "down" (pressed) state.  The optional third glyph is for when
     the button is disabled.  The last three glyphs are for displaying
     the button in the "up", "down", and "disabled" states,
     respectively, but are used when the user has called for captioned
     toolbar buttons (using `toolbar-buttons-captioned-p').  The
     function `toolbar-make-button-list' is useful in creating these
     glyph lists.

   * Even if you do not provide separate down-state and disabled-state
     glyphs, the user will still get visual feedback to indicate which
     state the button is in.  Buttons in the up-state are displayed
     with a shadowed border that gives a raised appearance to the
     button.  Buttons in the down-state are displayed with shadows that
     give a recessed appearance.  Buttons in the disabled state are
     displayed with no shadows, giving a 2-d effect.

   * If some of the toolbar glyphs are not provided, they inherit as
     follows:

               UP:                up
               DOWN:              down -> up
               DISABLED:          disabled -> up
               CAP-UP:            cap-up -> up
               CAP-DOWN:          cap-down -> cap-up -> down -> up
               CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up

   * The second element FUNCTION is a function to be called when the
     toolbar button is activated (i.e. when the mouse is released over
     the toolbar button, if the press occurred in the toolbar).  It can
     be any form accepted by `call-interactively', since this is how it
     is invoked.

   * The third element ENABLED-P specifies whether the toolbar button
     is enabled (disabled buttons do nothing when they are activated,
     and are displayed differently; see above).  It should be either a
     boolean or a form that evaluates to a boolean.

   * The fourth element HELP, if non-`nil', should be a string.  This
     string is displayed in the echo area when the mouse passes over the
     toolbar button.

   For the other vector formats (specifying blank areas of the toolbar):

   * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
     whether the area is displayed with shadows (giving it a raised,
     3-d appearance) or without shadows (giving it a flat appearance).

   * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
     area.  If omitted, it defaults to a device-specific value (8
     pixels for X devices).

 - Function: toolbar-make-button-list UP &optional DOWN DISABLED CAP-UP
          CAP-DOWN CAP-DISABLED
     This function calls `make-glyph' on each arg and returns a list of
     the results.  This is useful for setting the first argument of a
     toolbar button descriptor (typically, the result of this function
     is assigned to a symbol, which is specified as the first argument
     of the toolbar button descriptor).

 - Function: check-toolbar-button-syntax BUTTON &optional NOERROR
     Verify the syntax of entry BUTTON in a toolbar description list.
     If you want to verify the syntax of a toolbar description list as a
     whole, use `check-valid-instantiator' with a specifier type of
     `toolbar'.

Specifying the Toolbar
======================

   In order to specify the contents of a toolbar, set one of the
specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
`left-toolbar', or `right-toolbar'.  These are specifiers, which means
you set them with `set-specifier' and query them with `specifier-specs'
or `specifier-instance'.  You will get an error if you try to set them
using `setq'.  The valid instantiators for these specifiers are toolbar
descriptors, as described above.  See Specifiers for more
information.

   Most of the time, you will set `default-toolbar', which allows the
user to choose where the toolbar should go.

 - Specifier: default-toolbar
     The position of this toolbar is specified in the function
     `default-toolbar-position'.  If the corresponding
     position-specific toolbar (e.g. `top-toolbar' if
     `default-toolbar-position' is `top') does not specify a toolbar in
     a particular domain, then the value of `default-toolbar' in that
     domain, of any, will be used instead.

   Note that the toolbar at any particular position will not be
displayed unless its thickness (width or height, depending on
orientation) is non-zero and its visibility status is true.  The
thickness is controlled by the specifiers `top-toolbar-height',
`bottom-toolbar-height', `left-toolbar-width', and
`right-toolbar-width', and the visibility status is controlled by the
specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
`left-toolbar-visible-p', and `right-toolbar-visible-p' (see Other Toolbar Variables.).

 - Function: set-default-toolbar-position POSITION
     This function sets the position that the `default-toolbar' will be
     displayed at.  Valid positions are the symbols `top', `bottom',
     `left' and `right'.  What this actually does is set the fallback
     specifier for the position-specific specifier corresponding to the
     given position to `default-toolbar', and set the fallbacks for the
     other position-specific specifiers to `nil'.  It also does the
     same thing for the position-specific thickness and visibility
     specifiers, which inherit from one of `default-toolbar-height' or
     `default-toolbar-width', and from `default-toolbar-visible-p',
     respectively (see Other Toolbar Variables.).

 - Function: default-toolbar-position
     This function returns the position that the `default-toolbar' will
     be displayed at.

   You can also explicitly set a toolbar at a particular position.  When
redisplay determines what to display at a particular position in a
particular domain (i.e. window), it first consults the position-specific
toolbar.  If that does not yield a toolbar descriptor, the
`default-toolbar' is consulted if `default-toolbar-position' indicates
this position.

 - Specifier: top-toolbar
     Specifier for the toolbar at the top of the frame.

 - Specifier: bottom-toolbar
     Specifier for the toolbar at the bottom of the frame.

 - Specifier: left-toolbar
     Specifier for the toolbar at the left edge of the frame.

 - Specifier: right-toolbar
     Specifier for the toolbar at the right edge of the frame.

 - Function: toolbar-specifier-p OBJECT
     This function returns non-nil if OBJECT is a toolbar specifier.
     Toolbar specifiers are the actual objects contained in the toolbar
     variables described above, and their valid instantiators are
     toolbar descriptors (see Toolbar Descriptor Format.).

Other Toolbar Variables
=======================

   The variables to control the toolbar thickness, visibility status,
and captioned status are all specifiers.  See Specifiers.

 - Specifier: default-toolbar-height
     This specifies the height of the default toolbar, if it's oriented
     horizontally.  The position of the default toolbar is specified by
     the function `set-default-toolbar-position'.  If the corresponding
     position-specific toolbar thickness specifier (e.g.
     `top-toolbar-height' if `default-toolbar-position' is `top') does
     not specify a thickness in a particular domain (a window or a
     frame), then the value of `default-toolbar-height' or
     `default-toolbar-width' (depending on the toolbar orientation) in
     that domain, if any, will be used instead.

 - Specifier: default-toolbar-width
     This specifies the width of the default toolbar, if it's oriented
     vertically.  This behaves like `default-toolbar-height'.

   Note that `default-toolbar-height' is only used when
`default-toolbar-position' is `top' or `bottom', and
`default-toolbar-width' is only used when `default-toolbar-position' is
`left' or `right'.

 - Specifier: top-toolbar-height
     This specifies the height of the top toolbar.

 - Specifier: bottom-toolbar-height
     This specifies the height of the bottom toolbar.

 - Specifier: left-toolbar-width
     This specifies the width of the left toolbar.

 - Specifier: right-toolbar-width
     This specifies the width of the right toolbar.

   Note that all of the position-specific toolbar thickness specifiers
have a fallback value of zero when they do not correspond to the
default toolbar.  Therefore, you will have to set a non-zero thickness
value if you want a position-specific toolbar to be displayed.

 - Specifier: default-toolbar-visible-p
     This specifies whether the default toolbar is visible.  The
     position of the default toolbar is specified by the function
     `set-default-toolbar-position'.  If the corresponding
     position-specific toolbar visibility specifier (e.g.
     `top-toolbar-visible-p' if `default-toolbar-position' is `top')
     does not specify a visible-p value in a particular domain (a
     window or a frame), then the value of `default-toolbar-visible-p'
     in that domain, if any, will be used instead.

 - Specifier: top-toolbar-visible-p
     This specifies whether the top toolbar is visible.

 - Specifier: bottom-toolbar-visible-p
     This specifies whether the bottom toolbar is visible.

 - Specifier: left-toolbar-visible-p
     This specifies whether the left toolbar is visible.

 - Specifier: right-toolbar-visible-p
     This specifies whether the right toolbar is visible.

   `default-toolbar-visible-p' and all of the position-specific toolbar
visibility specifiers have a fallback value of true.

   Internally, toolbar thickness and visibility specifiers are
instantiated in both window and frame domains, for different purposes.
The value in the domain of a frame's selected window specifies the
actual toolbar thickness or visibility that you will see in that frame.
The value in the domain of a frame itself specifies the toolbar
thickness or visibility that is used in frame geometry calculations.

   Thus, for example, if you set the frame width to 80 characters and
the left toolbar width for that frame to 68 pixels, then the frame will
be sized to fit 80 characters plus a 68-pixel left toolbar.  If you then
set the left toolbar width to 0 for a particular buffer (or if that
buffer does not specify a left toolbar or has a nil value specified for
`left-toolbar-visible-p'), you will find that, when that buffer is
displayed in the selected window, the window will have a width of 86 or
87 characters - the frame is sized for a 68-pixel left toolbar but the
selected window specifies that the left toolbar is not visible, so it is
expanded to take up the slack.

 - Specifier: toolbar-buttons-captioned-p
     Whether toolbar buttons are captioned.  This affects which glyphs
     from a toolbar button descriptor are chosen.  See Toolbar Descriptor Format.

   You can also reset the toolbar to what it was when XEmacs started up.

 - Constant: initial-toolbar-spec
     The toolbar descriptor used to initialize `default-toolbar' at
     startup.

scrollbars
**********

   Not yet documented.

Major and Minor Modes
*********************

   A "mode" is a set of definitions that customize XEmacs and can be
turned on and off while you edit.  There are two varieties of modes:
"major modes", which are mutually exclusive and used for editing
particular kinds of text, and "minor modes", which provide features
that users can enable individually.

   This chapter describes how to write both major and minor modes, how
to indicate them in the modeline, and how they run hooks supplied by the
user.  For related topics such as keymaps and syntax tables, see
Keymaps, and Syntax Tables.

Major Modes
===========

   Major modes specialize XEmacs for editing particular kinds of text.
Each buffer has only one major mode at a time.

   The least specialized major mode is called "Fundamental mode".  This
mode has no mode-specific definitions or variable settings, so each
XEmacs command behaves in its default manner, and each option is in its
default state.  All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
<LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
keys.

   When you need to write several editing commands to help you perform a
specialized editing task, creating a new major mode is usually a good
idea.  In practice, writing a major mode is easy (in contrast to
writing a minor mode, which is often difficult).

   If the new mode is similar to an old one, it is often unwise to
modify the old one to serve two purposes, since it may become harder to
use and maintain.  Instead, copy and rename an existing major mode
definition and alter the copy--or define a "derived mode" (see
Derived Modes.).  For example, Rmail Edit mode, which is in
`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
mode except that it provides three additional commands.  Its definition
is distinct from that of Text mode, but was derived from it.

   Rmail Edit mode is an example of a case where one piece of text is
put temporarily into a different major mode so it can be edited in a
different way (with ordinary XEmacs commands rather than Rmail).  In
such cases, the temporary major mode usually has a command to switch
back to the buffer's usual mode (Rmail mode, in this case).  You might
be tempted to present the temporary redefinitions inside a recursive
edit and restore the usual ones when the user exits; but this is a bad
idea because it constrains the user's options when it is done in more
than one buffer: recursive edits must be exited most-recently-entered
first.  Using alternative major modes avoids this limitation.  See
Recursive Editing.

   The standard XEmacs Lisp library directory contains the code for
several major modes, in files including `text-mode.el', `texinfo.el',
`lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
libraries to see how modes are written.  Text mode is perhaps the
simplest major mode aside from Fundamental mode.  Rmail mode is a
complicated and specialized mode.

Major Mode Conventions
----------------------

   The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks.  Please follow these conventions when you
define a new major mode:

   * Define a command whose name ends in `-mode', with no arguments,
     that switches to the new mode in the current buffer.  This command
     should set up the keymap, syntax table, and local variables in an
     existing buffer without changing the buffer's text.

   * Write a documentation string for this command that describes the
     special commands available in this mode.  `C-h m'
     (`describe-mode') in your mode will display this string.

     The documentation string may include the special documentation
     substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
     enable the documentation to adapt automatically to the user's own
     key bindings.  See Keys in Documentation.

   * The major mode command should start by calling
     `kill-all-local-variables'.  This is what gets rid of the local
     variables of the major mode previously in effect.

   * The major mode command should set the variable `major-mode' to the
     major mode command symbol.  This is how `describe-mode' discovers
     which documentation to print.

   * The major mode command should set the variable `mode-name' to the
     "pretty" name of the mode, as a string.  This appears in the mode
     line.

   * Since all global names are in the same name space, all the global
     variables, constants, and functions that are part of the mode
     should have names that start with the major mode name (or with an
     abbreviation of it if the name is long).  See Style Tips.

   * The major mode should usually have its own keymap, which is used
     as the local keymap in all buffers in that mode.  The major mode
     function should call `use-local-map' to install this local map.
     See Active Keymaps, for more information.

     This keymap should be kept in a global variable named
     `MODENAME-mode-map'.  Normally the library that defines the mode
     sets this variable.

   * The mode may have its own syntax table or may share one with other
     related modes.  If it has its own syntax table, it should store
     this in a variable named `MODENAME-mode-syntax-table'.  See
     Syntax Tables.

   * The mode may have its own abbrev table or may share one with other
     related modes.  If it has its own abbrev table, it should store
     this in a variable named `MODENAME-mode-abbrev-table'.  See
     Abbrev Tables.

   * Use `defvar' to set mode-related variables, so that they are not
     reinitialized if they already have a value.  (Such reinitialization
     could discard customizations made by the user.)

   * To make a buffer-local binding for an Emacs customization
     variable, use `make-local-variable' in the major mode command, not
     `make-variable-buffer-local'.  The latter function would make the
     variable local to every buffer in which it is subsequently set,
     which would affect buffers that do not use this mode.  It is
     undesirable for a mode to have such global effects.  See
     Buffer-Local Variables.

     It's ok to use `make-variable-buffer-local', if you wish, for a
     variable used only within a single Lisp package.

   * Each major mode should have a "mode hook" named
     `MODENAME-mode-hook'.  The major mode command should run that
     hook, with `run-hooks', as the very last thing it does. See
     Hooks.

   * The major mode command may also run the hooks of some more basic
     modes.  For example, `indented-text-mode' runs `text-mode-hook' as
     well as `indented-text-mode-hook'.  It may run these other hooks
     immediately before the mode's own hook (that is, after everything
     else), or it may run them earlier.

   * If something special should be done if the user switches a buffer
     from this mode to any other major mode, the mode can set a local
     value for `change-major-mode-hook'.

   * If this mode is appropriate only for specially-prepared text, then
     the major mode command symbol should have a property named
     `mode-class' with value `special', put on as follows:

          (put 'funny-mode 'mode-class 'special)

     This tells XEmacs that new buffers created while the current
     buffer has Funny mode should not inherit Funny mode.  Modes such
     as Dired, Rmail, and Buffer List use this feature.

   * If you want to make the new mode the default for files with certain
     recognizable names, add an element to `auto-mode-alist' to select
     the mode for those file names.  If you define the mode command to
     autoload, you should add this element in the same file that calls
     `autoload'.  Otherwise, it is sufficient to add the element in the
     file that contains the mode definition.  See Auto Major Mode.

   * In the documentation, you should provide a sample `autoload' form
     and an example of how to add to `auto-mode-alist', that users can
     include in their `.emacs' files.

   * The top-level forms in the file defining the mode should be
     written so that they may be evaluated more than once without
     adverse consequences.  Even if you never load the file more than
     once, someone else will.

 - Variable: change-major-mode-hook
     This normal hook is run by `kill-all-local-variables' before it
     does anything else.  This gives major modes a way to arrange for
     something special to be done if the user switches to a different
     major mode.  For best results, make this variable buffer-local, so
     that it will disappear after doing its job and will not interfere
     with the subsequent major mode.  See Hooks.